
/*-------------------------------------------------------------------------
 *
 * lwlock.h
 *	  轻量级锁管理器
 *
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/storage/lwlock.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef LWLOCK_H
#define LWLOCK_H

#ifdef FRONTEND
#error "lwlock.h may not be included from frontend code"
#endif

#include "port/atomics.h"
#include "storage/proclist_types.h"

struct PGPROC;

/* 后台进程当前处于何种等待状态 */
typedef enum LWLockWaitState
{
	LW_WS_NOT_WAITING, /* 当前不在等待/已唤醒 */
	LW_WS_WAITING, /* 当前正在等待 */
	LW_WS_PENDING_WAKEUP /* 从等待列表中移除，但尚未发信号 */
} LWLockWaitState;

/*
 * lwlock.c之外的代码不应直接操作此结构的内容，
 * 但我们必须在这里声明它，以允许LWLocks被
 * 纳入其他数据结构。
 */
typedef struct LWLock
{
	uint16		tranche;		/* tranche ID */
	pg_atomic_uint32 state;		/* 独占/非独占锁的状态 */
	proclist_head waiters;		/* 等待的PGPROCs列表 */
#ifdef LOCK_DEBUG
	pg_atomic_uint32 nwaiters;	/* 等待者的数量 */
	struct PGPROC *owner;		/* 锁的最后独占所有者 */
#endif
} LWLock;

/*
 * 在大多数情况下，强制每个LWLocks的分组与缓存行边界对齐，并使数组
 * 步幅为2的幂是理想的。这可以节省索引中的几个周期，更重要的是确保
 * 单个LWLocks不会跨越缓存行边界。这减少了缓存竞争
 * 问题，特别是在AMD Opteron上。在某些情况下，添加
 * 更多填充是有用的，以使每个LWLock占用整个缓存行；
 * 例如，在主LWLock数组中，总的锁数量较少，但某些锁
 * 竞争严重时，这是有用的。
 */
#define LWLOCK_PADDED_SIZE	PG_CACHE_LINE_SIZE

/* LWLock，填充为完整的缓存行大小 */
typedef union LWLockPadded
{
	LWLock		lock;
	char		pad[LWLOCK_PADDED_SIZE];
} LWLockPadded;

extern PGDLLIMPORT LWLockPadded *MainLWLockArray;

/* 存储命名分组信息的结构 */
typedef struct NamedLWLockTranche
{
	int			trancheId;
	char	   *trancheName;
} NamedLWLockTranche;

extern PGDLLIMPORT NamedLWLockTranche *NamedLWLockTrancheArray;
extern PGDLLIMPORT int NamedLWLockTrancheRequests;

/* 固定lwlocks的名称 */
#include "storage/lwlocknames.h"

/*
 * 在这里声明NUM_BUFFER_PARTITIONS和NUM_LOCK_PARTITIONS有点奇怪，
 * 但我们需要它们来计算MainLWLockArray中的偏移量，而
 * 让这个文件包含lock.h或bufmgr.h是倒退的。
 */

/* 共享缓冲区映射哈希表的分区数量 */
#define NUM_BUFFER_PARTITIONS  128

/* 共享锁表被划分为的分区数量 */
#define LOG2_NUM_LOCK_PARTITIONS  4
#define NUM_LOCK_PARTITIONS  (1 << LOG2_NUM_LOCK_PARTITIONS)

/* 共享谓词锁表被划分为的分区数量 */
#define LOG2_NUM_PREDICATELOCK_PARTITIONS  4
#define NUM_PREDICATELOCK_PARTITIONS  (1 << LOG2_NUM_PREDICATELOCK_PARTITIONS)

/* 预分配的 lwlocks 各种块的偏移量。 */
#define BUFFER_MAPPING_LWLOCK_OFFSET	NUM_INDIVIDUAL_LWLOCKS
#define LOCK_MANAGER_LWLOCK_OFFSET		\
	(BUFFER_MAPPING_LWLOCK_OFFSET + NUM_BUFFER_PARTITIONS)
#define PREDICATELOCK_MANAGER_LWLOCK_OFFSET \
	(LOCK_MANAGER_LWLOCK_OFFSET + NUM_LOCK_PARTITIONS)
#define NUM_FIXED_LWLOCKS \
	(PREDICATELOCK_MANAGER_LWLOCK_OFFSET + NUM_PREDICATELOCK_PARTITIONS)

typedef enum LWLockMode
{
	LW_EXCLUSIVE,
	LW_SHARED,
	LW_WAIT_UNTIL_FREE			/* 在等待锁释放时，PGPROC->lwWaitMode 中使用的一种特殊模式。
								 * 不应作为 LWLockAcquire 的参数使用 */
} LWLockMode;


#ifdef LOCK_DEBUG
extern PGDLLIMPORT bool Trace_lwlocks;
#endif

extern bool LWLockAcquire(LWLock *lock, LWLockMode mode);
extern bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode);
extern bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode);
extern void LWLockRelease(LWLock *lock);
extern void LWLockReleaseClearVar(LWLock *lock, uint64 *valptr, uint64 val);
extern void LWLockReleaseAll(void);
extern bool LWLockHeldByMe(LWLock *lock);
extern bool LWLockAnyHeldByMe(LWLock *lock, int nlocks, size_t stride);
extern bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode);

extern bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval);
extern void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value);

extern Size LWLockShmemSize(void);
extern void CreateLWLocks(void);
extern void InitLWLockAccess(void);

extern const char *GetLWLockIdentifier(uint32 classId, uint16 eventId);

/*
 * 扩展（或核心代码）可以通过在 postmaster 启动期间调用
 * RequestNamedLWLockTranche() 来获取 LWLocks。随后，
 * 调用 GetNamedLWLockTranche() 获得指向包含请求的
 * LWLocks 数量的数组的指针。
 */
extern void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks);
extern LWLockPadded *GetNamedLWLockTranche(const char *tranche_name);

/*
 * 还有另一种更灵活的方法来获取 lwlocks。首先，仅调用一次
 * LWLockNewTrancheId 以获得一个 tranche ID；这会从
 * 一个共享计数器分配。接下来，每个使用该 tranche 的
 * 进程应该调用 LWLockRegisterTranche() 将该 tranche ID
 * 与一个名称关联。最后，每个 lwlock 只需调用一次
 * LWLockInitialize，将 tranche ID 作为参数传递。
 *
 * 似乎很奇怪，每个使用 tranche 的进程必须单独注册，但动态
 * 共享内存段不保证在所有协同的后端中以相同地址映射，因此
 * 在主共享内存段中存储注册信息在这种情况下不起作用。
 */
extern int	LWLockNewTrancheId(void);
extern void LWLockRegisterTranche(int tranche_id, const char *tranche_name);
extern void LWLockInitialize(LWLock *lock, int tranche_id);

/*
 * 每个小于 NUM_INDIVIDUAL_LWLOCKS 的 tranche ID 都是保留的；
 * 此外，我们还为未包含在单个 LWLocks 集合中的内置 tranche
 * 保留额外的 tranche ID。调用 LWLockNewTrancheId 将永远不会
 * 返回小于 LWTRANCHE_FIRST_USER_DEFINED 的值。
 */
typedef enum BuiltinTrancheIds
{
	LWTRANCHE_XACT_BUFFER = NUM_INDIVIDUAL_LWLOCKS,
	LWTRANCHE_COMMITTS_BUFFER,
	LWTRANCHE_SUBTRANS_BUFFER,
	LWTRANCHE_MULTIXACTOFFSET_BUFFER,
	LWTRANCHE_MULTIXACTMEMBER_BUFFER,
	LWTRANCHE_NOTIFY_BUFFER,
	LWTRANCHE_SERIAL_BUFFER,
	LWTRANCHE_WAL_INSERT,
	LWTRANCHE_BUFFER_CONTENT,
	LWTRANCHE_REPLICATION_ORIGIN_STATE,
	LWTRANCHE_REPLICATION_SLOT_IO,
	LWTRANCHE_LOCK_FASTPATH,
	LWTRANCHE_BUFFER_MAPPING,
	LWTRANCHE_LOCK_MANAGER,
	LWTRANCHE_PREDICATE_LOCK_MANAGER,
	LWTRANCHE_PARALLEL_HASH_JOIN,
	LWTRANCHE_PARALLEL_QUERY_DSA,
	LWTRANCHE_PER_SESSION_DSA,
	LWTRANCHE_PER_SESSION_RECORD_TYPE,
	LWTRANCHE_PER_SESSION_RECORD_TYPMOD,
	LWTRANCHE_SHARED_TUPLESTORE,
	LWTRANCHE_SHARED_TIDBITMAP,
	LWTRANCHE_PARALLEL_APPEND,
	LWTRANCHE_PER_XACT_PREDICATE_LIST,
	LWTRANCHE_PGSTATS_DSA,
	LWTRANCHE_PGSTATS_HASH,
	LWTRANCHE_PGSTATS_DATA,
	LWTRANCHE_FIRST_USER_DEFINED
}			BuiltinTrancheIds;

/*
 * 在 PostgreSQL 9.4 之前，我们使用一种称为 LWLockId 的枚举
 * 类型来引用 LWLocks。新代码应该使用 LWLock *。但是，出于
 * 第三方代码的便利，我们包含了以下 typedef。
 */
typedef LWLock *LWLockId;

#endif							/* LWLOCK_H */
